-
Notifications
You must be signed in to change notification settings - Fork 375
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(gnovm): Executable Markdown #2357
base: master
Are you sure you want to change the base?
Conversation
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## master #2357 +/- ##
==========================================
- Coverage 60.97% 60.45% -0.53%
==========================================
Files 564 562 -2
Lines 75273 74827 -446
==========================================
- Hits 45897 45235 -662
- Misses 26008 26204 +196
- Partials 3368 3388 +20
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. |
gnovm/pkg/doctest/exec.go
Outdated
// ExecuteCodeBlock executes a parsed code block and executes it in a gno VM. | ||
func ExecuteCodeBlock(c codeBlock, stdlibDir string) (string, error) { | ||
if c.lang == "go" { | ||
c.lang = "gno" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
since we don't have gno fully recognized by github atm, i suggest we also support something like
```go,gnodoctest
package foo
func main() {
a := 42
}
```
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changing 'go' to 'gno' (or using gno
) seems fine as it's intended to specify the file extension for temporary executable files.
However, I'm slightly concerned that including multiple elements on a single line when specifying the tag might break syntax highlighting during document rendering, especially using go
language tag.
If this isn't an issue, it might be useful to support specifying execution options like ignore
or should_panic
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice work -- I found this very well written and and easy to follow, but there is a lot here, so I've left plenty of comments regarding style and questions about certain things. Thanks for this 😄
Co-authored-by: deelawn <dboltz03@gmail.com>
Co-authored-by: deelawn <dboltz03@gmail.com>
Thank you for the detailed review @deelawn. I think I have addressed all the points you mentioned in your review. Could you please check and confirm? Thank you once again 👍 |
|
||
Doctest also recognizes that a block of code is a gno. The code below outputs the same result as the example above. | ||
|
||
```go |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This this a great idea, I have a few questions:
Do we intent to run both go code and gno code in the doctest?
How does Doctest detect this is a gno code?
What is the reason behind using "```go" instead of "````gno" for gno code block?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
That's a really good question. Currrently, when rendering markdown, gno doesn't have universal syntax highlighting applied yet (except the custom syntax rule). So, even in official documents like "Effective gno" are using go
instead of gno
to specify the language.
Considering the purpose of markdown is more for documentation rather than testing, this was an inevitable purpose. So I made it recognize both languages.
However, it doesn't clearly distinguish whether it's completely go
or gno
. For now, I assume that it's mostly compatible with go and execute it at gno VM level. In other words, even if the language is atually written in go, everything runs as gno. This part may require deeper context analysis in the future.
To summarize in the order of your questions:
- Even if the code block is specified as Go, it's actually recognized and executed as gno.
- There's no feature to clearly distinguish between the two languages, and it relies on the language specified in the fenced code block.
- Go is also set to be recognized due to syntax highlighting.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The main difference between Gno and Go is that Gno has a few native methods unique to blockchain usage. For example:
std.AssertOriginCall
std.GetHeight
Basically, a program can either be Go code or Gno code. We cannot mix them in one source file.
There are a few options I can think of
- Users need to explicitly mark it as either Go code or Gno code, similar to indicating the source code type with a suffix in the filename: xxx.go vs xxx.gno.
- Only support Gno.
- By default, the MD is treated as Gno code. Use gnostd.XXX to indicate that it is Go code. (Not sure if this has much practical purpose; it is more complicated to implement and is only for the sake of supporting Go code with chain functionality in MD.)
package main | ||
|
||
func main() { | ||
println("Hello, World!") |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
the println does not print correct results compared with file tests.
package main
type ints []int
func main() {
a := ints{1,2,3}
println(a)
}
doctest
// Output:
// (slice[(1 int),(2 int),(3 int)] gno.land/r/g14ch5q26mhx3jk5cxl88t278nper264ces4m8nt/run.ints)
file test result is correct. ints is a type defined in main package.
// Output:
// (slice[(1 int),(2 int),(3 int)] main.ints)
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It seems this is happening because the code is executed through the VMKeeper
.
func ExecuteCodeBlock(c codeBlock, stdlibDir string) (string, error) {
// ...
addr := crypto.AddressFromPreimage([]byte("addr1"))
acc := acck.NewAccountWithAddress(ctx, addr)
acck.SetAccount(ctx, acc)
msg2 := vm.NewMsgRun(addr, std.Coins{}, files)
res, err := vmk.Run(ctx, msg2)
// ...
}
I used this method to handle stdlibs imports. But honestly, I don't know how to maintain this functionality while also making it output main
.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
What about replacing it with the proper type when displaying the output in the Markdown?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the work to resolve my comments. Everything looks good to me.
Description
The
doctest
(tentative name) is a tool that allows code blocks in Markdown, especially those marked as "go" and "gno", to be executed using the gno VM.It works as follows: First, it parses the code blocks (fenced code blocks) from the Markdown file. After that, the extracted code is written to a temporary file, and the code is executed at the VM level.
Also supports static analysis to automatically include imports or packages without explicitly specifying them before execution. However, in this case, it assumes the code always executes the main function, fixes the package as 'main', and only searches for missing library paths in the standard library.
Additionally, to prevent unnecessary executions, a feature to cache execution results has been added.
I wrote the behavior and functionality in the file
gnovm/cmd/gno/testdata/doctest/1.md
as a tutorial.Moving forward, there is potential to further enhance this tool to support code documentation by allowing the execution of code embedded within comments, similar to Rust.
related #2245
CLI
The CLI command is used as follows:
path
literally means the path of the markdown file to be executed. Therun
flag allows you to specify a pattern to match against code block names or tags, similar togo test -run <name>
. This will execute all code blocks that partially or completely match the given pattern. Ifrun
is not specified, all code blocks in the file will be executed.The optional
timeout
flag allows you to set a maximum duration for the execution of each code block. If not specified, a default timeout will be used.For example:
This command will execute all code blocks in README.md that have "example" in their name or tag, with a timeout of 30 seconds for each block.